home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Plug-In Power Pack for Netscape Communicator
/
Plug-In Power Pack for Netscape Communicator.iso
/
plugins
/
dataviews
/
include
/
dvtypes.h
< prev
next >
Wrap
C/C++ Source or Header
|
1997-05-08
|
28KB
|
674 lines
/* file -- dvtypes.h
|===================================================================
|
| copyright (c) 1982
| Intelligent Software Systems, Inc.
|
| dvtypes.h
|
| Alan C Morse 3 Sept 82
|
| Alan C Morse 9 sept 82 Change color specifications
| Alan C Morse 28 Oct 8 Change slot count, add
| data buffering (3rd dim of
| data array), change
| df pointer to df table pointer.
| Alan C Morse 15 Nov 82 Change to reflect removal
| of instantiations.
| alan c morse 16 july 83 add foreground context color.
| alan c morse 19 april 84 add fval_mult_range.
| Marianne Smith 22 Jan 1991 Moved the definitions of values
| for flags in DF_DESC structure to
| dvstd.h
| mike krasnik 10 apr 91 changed VAR_DESC.range to double
| mike krasnik 12 apr 91 changed VAR_DESC.varsize to int
|
|===================================================================
|
| include-file description/function:
| Contains typedefs of data structures that are useful to
| DataViews. For instance, it contains the definition of the
| data group and variable descriptor data structures.
|
|===================================================================
*/
#ifndef DVTYPES_H
#define DVTYPES_H
/*
This describes the structure of the DataViews meta-display. It is
implemented as a linked list with forward and backward pointers.
This allows us to use the C alloc() and free() functions to add
space to the meta-display as necessary.
RULES / CONVENTIONS:
1) Argument blocks that are pointed to by a data group have the
following structure: a longword count, giving the size in bytes
of the argument block, followed by the argument block. The pointer
to this structure in the data group points to the beginning of the
argument block, skipping the longword that contains the count.
DataViews routine that free the space containing the copy of the
argument block must also remember to deallocate the longword.
2) To isolate display formatters from changes to datagroups once the
the display formatter has been invoked, we have the following rule:
Display formatters can only assume that the data group has current,
valid data on its initial call; it must make copies of all data that
it will need for future (update) calls.
*/
/*
ANYPTR typedef.
Typdef for use when a variable can be a pointer to
one of several scalar types.
*/
typedef union anydataptr
{
char *charptr;
char *cp;
UBYTE *ucp;
short *shortptr;
short *sp;
unsigned short *usp;
int *intptr;
LONG *longptr;
LONG *lp;
ULONG *ulp;
float *floatptr;
float *fp;
double *dblptr;
double *dp;
union anydataptr *ap;
} ANYPTR;
/*
ARRAY_WITH_COUNT typedef.
Typedef that standardizes the access to an array that is preceded
by a count, which tells the number of elements in the array. This
structure allows you to get the size of the array and to get the
base address of the array. If p is declared ARRAY_WITH_COUNT *p,
then the size of the array is p->elem_count and the base address
of the array is &p->first_elment.
*/
typedef struct ARRAY_WITH_COUNT
{
int elem_count; /* must be int at least for GRs_color_table() */
LONG first_element;
} ARRAY_WITH_COUNT;
/*
ATTR typedef.
Typedef of structure that describes the graphical attributes
associated with a variable. This is used in the VAR_DESC
data structure.
*/
typedef struct ATTR
{
UBYTE line_width; /* default = 1 */
UBYTE line_type; /* default = 0 = "solid" */
UBYTE area_fill; /* area fill pattern, tied to line type;
| default = 0 = "solid" */
UBYTE symbol; /* Symbol associated with the variable.
| This is a letter specifying a shape as follows:
| '.' = Point; 'R' = Rectangle; etc. */
short colcount; /* Number of colors to be associated with
| with the variable. If this count is zero, it means that the
| next longword contains a color specification for the
| variable. If the count is non-zero, it means that the next
| longword contains a pointer to a color threshold table. */
union
{
COLOR_THRESHOLD *colthreshp; /* Pointer to a table of thresholds
| and color specifications of type COLOR_THRESHOLD. */
COLOR_SPEC varcolor; /* color associated with variable
| The default color is color index i, where i is the index
| of the variable in the variable index list. */
} colorinfo;
} ATTR; /* Attributes to be associated with the variable */
/*
DF_DESC typedef.
Typdef for a structure linking the data group to a display formatter.
*/
typedef struct DF_DESC
{
ENTRY_PT *(*df_jumptable) V_P_((ENTRY_PT*)); /* Pointer to a function that
| returns the table of entry points for the graph */
ENTRY_PT *df_table; /* Pointer to a fixed size array of
| pointers to entry points in a display formatter. The indices
| indicate what type of call to the display formatter
| this is. Some of the possible types of calls are: Initial
| call, display update call, error call, cleanup heap call. The
| indices that correspond to each type of call is fixed system-
| wide, and is defined using parameters. This table is assumed
| to be static; that is, it isn't in the heap. So when a copy
| is made of DF_DESC data structure, this pointer is simply
| copied. We should not allocate space for and make a copy
| of the jumptable. (This means that this space should not
| be freed when the DF_DESC is deleted.) */
ENTRY_PT disp_formatter; /* Pointer to the current
| display formatter (DF) entry point.
| This routine expects a single argument, a pointer to a data
| structure of type DATAGROUP. This is one of the entry points
| from the above array. Initially, it is the first entry in the
| above array. Then the display formatter sets it to something
| else, depending on the results of its first attempt at drawing
| the data described by the dg. */
ADDRESS dfargs; /* Pointer to a count and an array of
| NAME_VALUE_PAIRs that are used to pass arguments to
| display formatters. The interpretation of these pairs
| is highly display formatter-dependent. The count is
| a short giving the number of pairs immediately following. */
ADDRESS ptemp_area ; /* Pointer to a temporary storage area
| for use by the display formatter.
| The data that this points to must be freed from the heap
| by an entry point in the display formatter module, which
| entry point gets called when the display formatter gets
| disconnected from the data group. */
ADDRESS data_buff; /* Pointer to data buffer used by
| display formatter. */
ULONG flags; /* Flags that reflect the current status of
| the datagroup. */
} DF_DESC;
/*
LINKS typedef.
Typdef describing the DataViews standard structure for implementing
doubly linked list.
*/
typedef struct linkstruct
{
struct linkstruct *next;/* Ptr to next entry in linked list. */
struct linkstruct *prev;/* Ptr to previous entry in linked list*/
short checkf; /* Flag containing a constant that tells the type
| of linked list entry. For instance, this number might be
| a constant that says, "I am a datagroup descriptor."
| This constant should be set to the appropriate value when the
| linked list entry is created (allocated). */
} LINKS;
/*
TIC_DATA typedef.
Typedef of structure used by axis tic makers. This structure
contains intermediate as well as final results from tic
position calculations. This structure allows the user to
initialize certain parameters to influence where tic marks
get placed and how they get labelled.
Those data that can be preset to constrain the tic calculations are:
1) Data range (must be set by caller).
2) Minimum minor and major tic mark gaps, in either pixel space or
value space (or both). One of these four must be specified
(greater than zero).
3) base_exponent. If this is preset, then it gives the minimum
value that the base_exponent can have.
4) ticratio can be set, constraining the number of minor tic
marks per major tic mark. The only acceptable values are
1, 2, 5 or 10.
5) The type of the first tic mark. Must be in range [0,ticratio).
This allows forcing the first tic mark to be a major tic mark
by setting first_tic_type to zero.
Flags are used to tell which of these has been preset when it
can't be obvious from the data value. Non-zero values indicate
preset data for items 2 and 4. 3 and 5 use flags.
*/
typedef struct TIC_DATA
{
struct
{
unsigned fbase_exp: 1; /* Base exponent has been set */
unsigned ffirst_tic_type: 1; /* First tic type has been set */
unsigned is_filled_in: 1; /* All the data has been filled in the
| TIC_DATA data structure by call to VXtdsetup. */
unsigned minimum_ticks: 1; /* The axis has the minimum number of
| tick marks; either a single tick mark (if pgap = 0) or
| two tick marks, one at each end. */
unsigned IsLogScale;
} tdflags; /* Says which data in the
| in the data structure has been initialized.
| Data that has not been initialized gets default values,
| or values that are extracted from the data group. */
double vmin, vmax; /* Range of data values. */
double axmin, axmax; /* Range of axis values.
| For linear data, these are the same as vmin, and vmax.
| For log data, these are log(vmin) and log(vmax). */
short axis_length; /* Length of axis in pixel space. */
struct /* Minimum distances in pixel space between ... */
{
short sminor; /* minor and ...*/
short smajor; /* major tic marks. */
} pgap_min;
struct /* Minimum differences in data values between ...*/
{
double fminor; /* adjacent minor and ... */
double fmajor; /* major tic marks. */
} vgap_min;
short base_exponent; /* Power of ten that is the basis for the
| differences in value between adjacent tic marks. Actual
| differences are factors of 1, 2, 5, or 10 times
| 10 raised to this value. */
struct /* Ratio of increments in data value of ... */
{
char tminor; /* minor and ... */
char tmajor; /* major tic marks values to the basis scale. */
} ticbase_ratio;
char ticratio; /* Ratio of major to minor
| tic data value increments. */
char first_tic_type; /* Type of first tic mark: 0 means "major";
| 0 < i < ticratio means the i-th minor tic mark. */
double vgap; /* Data value increment that corresponds to one minor
| tic mark gap. */
double vinitial; /* Data value that corresponds to the first tic
| mark (minor or major). */
double pgap; /* Pixel distance between adjacent minor tic marks. */
double poffset; /* Pixel distance to first tic mark
| (minor or major). */
} TIC_DATA;
typedef void (*DV_TICLABELFUNPTR) V_P_((ADDRESS argpcopy, double *value,
ADDRESS output, TIC_DATA *tdp));
/*
TICLABELLER_DESC typedef.
Typedef of the structure that describes how the axis tic marks are
to be labelled. The TIC_DATA data structure describes how the tic
marks are to be placed and what values correspond to each tic mark.
These values can be mapped via a user-supplied function to
character strings for labelling the tic marks; otherwise the value
is used as a label.
*/
typedef struct TICLABELLER_DESC
{
TIC_DATA *ptic_data; /* Pointer to a structure that describes
| where the tic marks are to go and what data values are
| associated with them. These associated values are used to
| determine how they are to be labelled. */
DV_TICLABELFUNPTR pval_to_string; /* Ptr to a function that takes as
| arguments 1) a pointer to an argument list (specified below);
| 2) a pointer to a double precision value; 3) a pointer
| to a character array to receive the resulting string;
| and 4) a pointer to the relevant TIC_DATA data structure
| (if any).
| The routine must provide a way of finding out the longest
| possible string that can be returned. The arguments to
| find this out are: 1) the same pointer as above, 2) a NULL
| pointer, 3) a pointer to a longword to receive the
| length of the longest string that the function will generate,
| and 4) a pointer to the appropriate TIC_DATA data structure.
| This latter type of call will also initialize appropriate
| arguments in the pvtos_args argument list. */
ADDRESS pvtos_args; /* Pointer to an argument list for the above
| function. This follows the DataViews conventions for
| handling pointers to argument lists, namely, that the size
| in bytes of the argument list precedes the argument list,
| and the argument list cannot point to allocated structures
| that nobody is going to know how to deallocate. */
} TICLABELLER_DESC;
/*
GRID_ATTR typdef.
Axis Grid attributes:
1) color,
2) line type,
3) and line width.
*/
typedef struct
{
COLOR_SPEC Color;
char LineType;
char LineWidth;
} GRID_ATTR;
/*
AXIS_DESC typedef.
This contains information about an axis:
1) Its label.
2) How the tick marks are to drawn and labelled.
3) The grid (if any) attributes.
*/
typedef struct
{
char *label; /* Ptr to label for the variable's value axis
| If this pointer is NULL then there is no value axis label. */
TICLABELLER_DESC *ticks; /* Ptr to structure that describes
| the axis tic mark labelling. If this pointer is NULL then
| it means that the default axis tic mark labelling should be
| used. */
GRID_ATTR GridAttr;/* Axis Grid attributes */
} AXIS_DESC;
/*
DG_AXES typedef.
Typedef for the stuff that describes how the datagroup's axes are to
be labelled. This only includes those axes that apply to the
data group as a whole, namely, the 2 dimension axes and the time axis.
*/
typedef struct DG_AXES
{
AXIS_DESC *TimeAxis; /* Info describing time axis */
/* Time axis tick mark labelling info */
float TimeStart, TimeIncrement; /* Describes values associated with
| time slot positions. Normally, the system labels the time
| slots consecutively (i.e., increment is 1) starting with 1.
| If the Increment is zero, then it means to use the default. */
AXIS_DESC *D1Axis; /* The first space dimension axis */
AXIS_DESC *D2Axis; /* The second space dimension axis */
} DG_AXES;
/* V_DGP_CONSECUTIVE_TIME_AXIS */
/* MACRO to test if time axis labels slots with consecutive integers. */
/* This is a superset of the default case and means that TimeStart is */
/* an integer and TimeIncrement is 1.0. */
/* This yields a boolean (YES/NO) result. */
/* This requires that <math.h> be included. */
#define V_DGP_CONSECUTIVE_TIME_AXIS( dgp ) \
( ((DATA_GROUP*)dgp)->axinfo->TimeIncrement == 1.0 && \
((DATA_GROUP*)dgp)->axinfo->TimeStart == \
S_FLOOR( ((DATA_GROUP*)dgp)->axinfo->TimeStart ) )
/* V_DGDF_NO_MINOR_TIME_TICS */
/* Macro to test if we are to put minor ticks on the time axis. */
/* For graphs with time slots, it may not make sense to put these ticks */
/* in. This is true if the ticks are integers that are sequential */
#define V_DGDF_NO_MINOR_TIME_TICS V_DGP_CONSECUTIVE_TIME_AXIS
/*
VAR_DESC typedef.
Typdef for the descriptor for each variable in the data group.
There is a linked list of these descriptors for each data group.
*/
#ifdef VAR_DESC
# undef VAR_DESC
#endif
typedef struct vdstruct
{
LINKS link;
short refcount; /* Number of references to this structure */
ANYTYPE *pvar; /* Ptr to base address of variable, which may not
| actually be LONG integer. */
struct
{
int d1; /* Size of variable in dimension 1. default: 1 */
int d2; /* Size of variable in dimension 2. default: 1 */
int d3; /* Size of variable in dimension 3. default: 1 */
} varsize; /* All the variables in the data group
| ought to be the same size. Different size variables
| should be simulated using access functions.
| Conceptually, all variables are vectors of time slices of
| of 2D data. d3 gives the number of time slices, d2 gives
| the number of rows, and d1 gives the number of columns.
| In C, this means that d1 index changes the fastest and is
| the rightmost index. Thus, a single
| scalar has (d3,d2,d1) = (1,1,1);
| a buffered scalar has (n,1,1);
| a single time slice of a vector has (1,n,1) or (1,1,n); etc.
| matrices, and vectors are n by 1 matrices. */
ADDRESS pvaraccess; /* Ptr to access function (if any) for the
| variable. This function is supposed to return an integer
| in the range [0,32767] if the value is to be normalized, or
| a pointer to a float if the value is not to be normalized.
| (The number is usually normalized and converted to integer
| to improve speed.) If for some reason the variable has an
| undefined value, this routine returns a -1.
|
| This function always takes as arguments
| a ptr to an access block (structure of arguments describing
| the variable, see pva_args described next), and three array
| indices, which may be ignored by the access function and which
| will be zero if the variable has associated dimension of one.
| If the first array index to the function is -1, then the
| function should return the next value (normalized) in the
| variable's array.
| If the first array index is -2, the access function should
| return a pointer to a float containing the actual value
| that was last accessed.
| The default for this function is the normal sequential access
| function for the corresponding data type and dimension of this
| variable. */
ADDRESS pva_args; /* Pointer to structure that the variable access
| function uses to facilitate access to the variable. Since the
| structure varies according to the access function, we declare
| simply as a generic pointer (ADDRESS). The space pointed to
| must be freed (deallocated) before this variable descriptor can
| be deleted. */
UBYTE vartype; /* flag indicating type of the variable. The
| possible values are:
| 0 = "unknown"
| 1 = "CHAR integer"
| 2 = "unsigned CHAR integer"
| 3 = "SHORT integer"
| 4 = "USHORT integer"
| 5 = "LONG integer"
| 6 = "ULONG integer"
| 7 = "float"
| 8 = "double-precision float"
| 9 = "text string" (NULL-terminated) */
UBYTE varaccess; /* flag indicating type of access to variable.
| 0 = direct access - base address points to actual data
| 1 = indirect access - base points to pointer to
| actual data.
| 3 = indirect access and bound to a DataViews datasource,
| which needs to be notified when deleting.
| NOTE this field also encodes whether the variable is
| a log variable. The 5th bit from the right is used
| to encode this (i.e., 0x10 masks the bit
| The default for this variable is "direct access"
| "not a log," that is, varaccess is zero */
UBYTE vd_is_in_dg; /* Flag saying whether the vdp is in a linked list
| that has a DATAGROUP at its head. This is YES if it is part
| of DATAGROUP, NO otherwise. */
struct
{
double lo;
double hi;
} range; /* Range of data values to be encoded. */
ATTR attr; /* Graphical attributes associated with the variable.*/
char *pvarname; /* Ptr to text string that names the variable. */
AXIS_DESC *axis; /* Information describing how the axis is to
| to be labelled, marked with ticks, and gridded.
| If this pointer is NULL and this variable descriptor
| is the first in the list of variable descriptors associated
| with a data group then it means that there is no axis information.
| If the pointer is NULL and this is not the first variable
| descriptor then it means: "use the value axis information
| from the first variable descriptor in the list." */
} VAR_DESC;
/*
CONTEXT_FLAGS typedef.
Context control flags for a graph (DATAGROUP).
*/
typedef struct
{
unsigned fpre_erase: 1; /* If set, it means the display
| formatter should clear the viewport before initially
| drawing into it. If this is not set, the display
| formatter will overlay whatever is already on the screen
| in the display viewport. This doesn't guarantee that
| repeated calls to the display formatter will result in a
| clean overlay. The display formatter will have to do some
| erasing in updating the display. Default: YES */
unsigned fcontext: 1; /* Put up display context. If NO, all
| that is to appear is the display of the encoded data.
| This overrides the settings for all the flags below.
| They are treated as if the were set to NO, if this is set
| to NO. Default: YES */
unsigned flegend: 1; /* Put up the legend. Default: YES */
unsigned fvpbox: 1; /* Draw a box around the datagroup viewport
| Default: YES */
/*
Flags that control the quality of the time axis labelling.
*/
unsigned ftim_tics: 1; /* Draw tic marks? Default: NO */
unsigned ftim_mintics: 1; /* If we're drawing tic marks, do
| we draw the minimum number of tic marks, namely, one at
| each end of the axis, giving the minimum and maximum values
| for the data? Default: NO */
unsigned ftim_label_tics: 1; /* If we have tic marks, do we
| label them? Default: NO */
/*
Flags that control the quality of the d1 axis labelling.
*/
unsigned fd1_tics: 1; /* Draw tic marks? Default: NO */
unsigned fd1_mintics: 1; /* If we're drawing tic marks, do
| we draw the minimum number of tic marks, namely, one at
| each end of the axis, giving the minimum and maximum values
| for the data? Default: NO */
unsigned fd1_label_tics: 1; /* If we have tic marks, do we label
| them? Default: NO */
/*
Flags that control the quality of the d2 axis labelling.
*/
unsigned fd2_tics: 1; /* Draw tic marks? Default: NO */
unsigned fd2_mintics: 1; /* If we're drawing tic marks, do
| we draw the minimum number of tic marks, namely, one at
| each end of the axis, giving the minimum and maximum values
| for the data? Default: NO */
unsigned fd2_label_tics: 1; /* If we have tic marks, do we label
| them? Default: NO */
/*
Flags that control the quality of the value axis labelling.
*/
unsigned fval_tics: 1; /* Draw tic marks? Default: NO */
unsigned fval_mintics: 1; /* If we're drawing tic marks, do
| we draw the minimum number of tic marks, namely, one at
| each end of the axis, giving the minimum and maximum values
| for the data? Default: NO */
unsigned fval_label_tics: 1; /* If we have tic marks, do we
| label them? Default: NO */
unsigned fval_mult_range: 1; /* Do we allow multiple value
| ranges? If yes, then each variable will be displayed
| by scaling to its own range. If no, a common range
| for all the variables will be determined, which range
| encompasses all the ranges, and this range will be
| used by the display formatter for all variables.
| The default for this flag is YES. */
/*
Flags that control grids in graphs.
*/
unsigned ftime_grid: 1; /* Should we display a grid for the
| time axis. */
unsigned fval_grid: 1; /* Should we display a grid for the
| value axis. */
} CONTEXT_FLAGS;
/*
DATAGROUP typedef.
Typdef of the top-level structure in the data structure that describes
a DataViews data group. The meta-display comprises a linked list of
of the structures of this type.
*/
#ifndef DATAGROUP
#define DATAGROUP ADDRESS
#endif
typedef struct dgstructure
{
LINKS link;
char *dgtitle; /* Pointer to title for labelling the display
| of the data group's data. */
DG_AXES *axinfo; /* Pointer to info describing the axis labels */
LONG flags; /* Control display of context of graph */
short numvar; /* Number of data variables in this data group. */
VAR_DESC *pvardesc; /* Ptr to the first descriptor in a
| linked list of descriptors that describe each variable
| in the data group. There are numvar of these structures. */
FLOAT_POINT vpll, vpur; /* Lower left and upper right coordinates
| of the datagroup stored in Normalized Device Coordinates
| ( in the range from 0.0 to 1.0 ). */
COLOR_SPEC backcolor; /* Background color, default is black
| ( zero color table index value )*/
COLOR_SPEC forecolor; /* Foreground color, used for drawing
| the display context; the default is half intensity grey. */
UBYTE devndx; /* Index of device on which to display
| the data. This index is into an array of device numbers
| maintained by DataViews. Users insert the numbers into the
| array implicitly when they open the devices. */
short slotcount; /* Number of time slices that are to fit into
| one data display. For an animated display, this is one.
| For a datagroup for which the 100 most recent values are
| to be displayed, this would be 100. */
short buffernum; /* Number of data elements to be stored
| in the graphs data buffer. By default buffernum is
| set to slotcount. A constraint is that buffernum cannot
| be less than slotcount - since enough data must be buffered
| so that the graph can be redrawn. */
short ScrollAmount; /* Number of time slices to scroll the
| display when it fills up and there is no more room
| for history data. For graphs that can display history
| the following values make sense:
| ScrollAmount = 0 means "wrap around"
| ScrollAmount = 1 means "scroll left one slot"
| (this is a strip chart)
| ScrollAmount = n, where 1 <= n < slotcount means
| scroll left n slots, leaving n slots empty.
| ScrollAmount = slotcount means "erase all slots"
*/
DF_DESC *pdfd; /* Pointer to a display formatter descriptor,
| which will be NULL in cases where no display formatter
| has been linked to the datagroup. */
} DATA_GROUP;
#endif /* DVTYPES_H*/
